Belgian Amiga Club - ADF Collection/BS1 part 26.zip/BS1 part 26/Aztec C v5.2a disk 2.adf/lharc.doc

Text File | 1991-10-22 | 28KB | 706 lines

________________________________________________________________________
------------------------------------------------------------------------


                        LHARC        vers. 1.21

                        for the Commodore AMIGA
         Compatible with version 1.13 of Lharc for MSDOS systems

                  by Paolo Zibetti   (FidoNet 2:331/101.6)
                  (assembler routines by  Paolo Toccaceli)


------------------------------------------------------------------------
 IMPORTANT NOTICE:  This program is copyrighted by Paolo Zibetti, but can
 be freely distributed, providing that the following rules are respected.
 - No change is made to the program nor to the accompaning documentation
 - The package is always distributed in its complete form consisting of
   3 files: "Lharc", "Lharc.doc" and "Changes".
 - Every form of distribution is allowed and encouraged, but no fee can
   be charged for this program exept for, possibly, the cost of magnetic
   media and/or disk duplication and shipping.
 - Inclusion in PD software libraries such as Fish Disks is allowed,
   provided the fees charged for theese disks are comparable with those
   charged by Fred Fish.
 - The program cannot be distributed in any commercial product without the
   written consent of the author.
 By copying, distributing and/or using the program you indicate your
 acceptance of the above rules.
 Also remember that this program is supplied 'as is': the entire risk as
 to the quality of the program is to the user. In no event will the author
 be liable for direct or indirect damage or loss resulting from the use
 of this program.
------------------------------------------------------------------------

________________________________________________________________________
------------------------------------------------------------------------










 --- Introduction ---

Lharc is an archive program such as Arc and Zoo. It can store several
files in one archive in a compressed form which is generally more
efficent than that used by Arc and Zoo.  It also supplies all of the
archive handling capabilities that an archive program should have.
In particular it is able to store an entire directory tree
with one single command. This enables you, for example, to store an
entire floppy-disk with a single command creating an archive which is
usually shorter than those prodeced by Warp or even LhWarp (see the -r
switch).
Another important feature of Lharc is its ability to preserve the file
attributes (see the -a switch) and filenotes (i.e. the comments that
AmigaODS can associate to each file).
Its only weakness is compression speed: Zoo 2.0, for example, is
faster, but if compression efficency is more important for you than
compression time you'll surely appreciate this progam. (anyway
decompression is much faster than compression)










 --- Before starting ---

Lharc is a 'pure' program, i.e. you can make it resident via the
'resident' Amigados command just like any other command found in the
c: directory. Keeping Lharc resident will greatly facilitate users
who make an heavy use of Lharc (especially those who don't have an
hard disk).
If you have just received Lharc, beware that some copy programs and
some archivers (including the zoo archiver which is used for
distribution of Lharc) don't preserve file attributes, so the 'p'
flag may not be set for the Lharc executable and Amigados won't
understand that Lharc is a pure program. If so, just type the
following line at the CLI prompt:

 protect Lharc p add










 --- How to use ---

Lharc is run from CLI with the following command line:

  Lharc [<switches>] <Command> <Archive> [<dest path>] [<file patterns>]

items in square brackets are optional.




<Command> can be any of the following (case is not significant):


  e,x  extract files from archive
       Extracts files from archives. If you specify some file names
       or patterns only those files satisfying the patterns are
       extracted, otherwise all the files in the archive are
       extracted.
       While extracting files, Lharc checks if a file by the same
       name already exsists in the destination directory and prompts
       you before overwriting the old file with the extracted one
       (unless you specified the -m switch)
       By default, if the files have a path name stored in the archive, they
       are extracted with their path and needed directories
       are automatically created; use the -x0 switch to ignore path names.
       See below under '<dest path>' for a discussion on where the
       extracted files are stored.

  l    show archives contents
       Displays the names of the files in an archive along with their
       date, time, CRC, compression type, original lenght and
       compressed lenght.
       If the -x switch is specified file names are listed complete
       with their path (if present in the archive), otherwise
       only the name of the files is listed.
       The 'l' command won't list the comments (filenotes) that may be
       assiciated with a file: use the 'v' command to see them, too.

  v    Same as 'l', but default is to display full pathnames: i.e.
       the 'v' command is equivalent to the 'l' command with the -x switch;
       on the other hand the 'l' command is equivalent to the 'v' command
       with the -x0 switch.
       Moreover 'v' will also show any filenote (i.e. comment)
       associated with the files; filenotes, if present,
       are listed on a separate line preceded by a colon
       (i.e. in the same format used by the AmigaDOS 'list' command).

  p    extract and print files to screen
       same as 'e' and 'x', but extracted files are sent to stdout

  t    test archive integrity
       Checks CRCs and checksums to ensure that the archive is not
       corrupted. Lharc will test all the files on the archive, one
       after each other, printing "OK" to the right of the file names
       which are OK and "WARNING: CRC check failed" to the right of
       file names that are corrupted. At the end of the test the
       message "Operation successful" means that all the files tested
       were OK, while the message "Operation not totally successful"
       means that some files in the archive were corrupted (so you
       will know of a corrupted file even if the warning message
       relating to that file has scrolled away on the screen)

  a    create archives or add to existing archives
       Files are stored in alphabetical order, unless you change
       this with the -S switch. Note however that sorting only
       applies to the files beeing added in the current session,
       i.e. if you add files to an existing archive containing
       other files, the new files will be stored, in alphabetical
       order, AT THE END of the archive: old and new files won't be
       intermixed to preserve global alphabetical order.
       If you try to archive a file and a file by the same name
       already exists in the archive the file will not be added
       and a message will be printed on the screen to inform you.
       By default only file names are stored in the archive, use the
       -x switch to store file names complete with their paths.
       Also, by default file attributes are not stored, use the '-a'
       switch to obtain this.

  m    move files into archivs
       Same as add, but deletes original files after archiving them

  d    delete files from archives
       You can delete from an archive a maximum of 150 files at a time,
       if you find that they are too little, please let me know!

  u    update files in archives
       Same as with the 'a' command.  However, if a file already
       exists in the archive, LHarc will check its time stamp and will
       keep the newer one and ignore the older one.

  f    freshen files in archives
       Replaces a file in the archive with the newer one only if a file
       with the same name already exists in the archive.
       Otherwise, no action is taken.







<Archive> is the name (eventually preceded by a path) of the
archive you want to work on. If no extension is specified the default
extension .LZH is used.
With the 'l' (or 'v'), 'e' (or 'x'), 'p', 't' and 'a' commands you can
work on multiple archives by using wildcards (see 'file patterns'
below for a list of accepted wildcards). For example "lharc v *.LZH"
will show the contents of all the archives in the current directory,
while "lharc x *.LZH *.c" will extract all the C source files
contained in all the archives in the current directory.






[<dest path>]
This parameter is significant only with the 'x' (or 'e') command and is
ignored otherwise. It tells where to put the extracted files; if not
specified, extracted files will go to the current directory.
Please note that this paramenter must always end with '/' or ':'
otherwise it will not be recognized as such and will be considered
as one of the file patterns.
If the path specified by <dest path> (or equivalently the path stored
in the archive) does not already exist, you will be prompted if you
want new directories to be automatically created (unless you specified
the -m switch, in which case directories will be created without any
prompt).






[<file patterns>] rappresents an optional number of file names
or file patterns. They indicate which files to
extract/compress/list/delete, ecc.
Accepted wild cards are the standard AmigaDOS '#' and '?' plus the '*'
which is a synonim of '#?'. Since however the asterisk is a valid
caracter in AmigaDOS file names I provided the '**' sequence as an
escape.  So if you want to refer to a file name containing an asterisk
just double the asterisk in the file name.
Example:  '*.c' is equivalent to '#?.c' and refers to all the files
ending with '.c', while 'my**file' refers to the file 'my*file'.






[<switches>] rappresents an optional number of switches that are used
to change the behaviour of the program.
A switch is composed by  a leading '-' followed by one letter; unlike
commands which are case insensitive, switches are case sensitive.
An important point is that if you want to specify more than one switch,
every switch must be preceded by its own dash, i.e. to activate the 'x'
and 'm' switches you must enter "-x -m" and NOT "-xm".
You can store your favourite switch configuration in an environment
variable (see below) so that you don't have to type them every time.
All the switches that don't take a parameter can be followed by a '0'
which turns off the function, while the switch alone or the switch
followed by a '1' turns the function on: i.e. -x means "use extended
file names",  while -x0 means "don't use them". So you can override
the default settings or the settings you specified in the environment
variable "LHARC".
Default value for every switch is off, exept for the -x switch which is
by default on with the 'x' 'e' 'd' and 'v' commands and off with the
other  commands.

Here is a summary of the available switches:


  -p  Pause after loading        [note that this is lowercase 'p']
      Causes Lharc to wait for the user to press RETURN before
      executing a command. This allows floppy disk users to swap disks
      after loading Lharc.

  -m  no Message for query
      Suppresses all the queries Lharc normally issues before
      overwriting existing files or before creating new directories
      If you specify this switch Lharc will behave as if you choose
      the default action (indicated by an uppercase letter) in
      response to all the questions. This switch also disables
      autoshowing of files (see 'Autoshow files' below)

  -x  use eXtended file names
      By default, LHarc stores only the file names of
      files and disregards the names of the directories in which
      they reside.  This switch, used with the 'a' command, tells LHarc
      to extend all file names with directory names; with the 'x' 'e' 'd'
      and 'v' commands the -x switch is automatically turned on: use
      -x0 if you want to turn it off thus ignoring pathnames with these
      commands.

  -n  No progress indicator
      Suppresses the display of the number of bytes beeing processed
      during compression or decompression. May be useful if you
      redirect to a file the output of Lharc.
      Note: this version of Lharc allows the -N switch as a synonim of -n :
      but this might change in future versions, so preferibly use the
      lowercase letter.

  -w  set Work directory
      Use this switch to choose your own directory for temporary files.
      The directory name must immediatly follow the letter 'w' without
      any leading space, i.e. to set the 'temp' directory on your
      hard-disk as the working directory you must write "-wdh0:temp".
      See below "Temporary files" for a discussion on where temporary
      files are stored in the absence of this switch.

  -P  set Priority          [note that this is uppercase 'P']
      Use this switch to set the priority with which Lharc will be
      executed. Priority must be in the range -5..+5  and must
      immediately follow the 'P' letter without blanks in between.
      By default Lharc is excuted with the same priority of
      the task that invoked it; using this switch will set the new
      priority immediatley after loading and will set back the priority
      to the original value immediately after terminating.
      If you want to do something else with your Amiga, for example
      editing a letter, while Lharc is compressing a long file, I
      suggest that you set Lharc's priority to one less than that of
      the other program, i.e. if you started your editor with the usual
      priority of zero then invoke Lharc with the '-P-1' switch to set its
      priority to -1

  -a  consider file Attributes
      By default Lharc will ignore file attributes (i.e. the flags
      indicating protection from deletion, and so on) for maximum
      compatibility with the MSDOS version: in other words it will
      store files with an attribute bit pattern which is suitable for
      MSDOS machines while during extraction it will ignore the
      attributes stored in the archives, setting the attributes of the
      extracted files to the usual '----rwed'.
      If you use this switch, on the contrary, files will be stored
      with their original attributes and during extraction the
      stored attributed will be restored.
      Remember that, to effectively preserve file attributes, you must
      use this switch both during compression and during extraction.
      Of course AmigaDOS file attributes are meaningless to MSDOS and
      vice-versa; so extract files with the -a switch only if you are
      sure that they contain AmigaDOS file attributes and similarly
      compress files with the -a switch only if you are sure that the
      archive will be unpacked only by Amigas and not by MSDOS
      machines. (Anyway no harm is done if this rule is not respected:
      extracted files will simply have strange attributes)

  -u  convert file names to Uppercase
      By default Lharc stores file names/paths with thier original case,
      if you use this switch they will be converted to uppercase.
      See below 'Compatibility' for a possible use of this switch.

  -r  Recursively collect files
      This switch instructs Lharc to search for files matching the
      specified patterns not only in the specified directories, but also
      in all the subdirectories that may be found in the specified
      directories. For example: "Lharc -r a archive.lzh df1:source/*.c"
      will search for files whose name ends with ".c" in "df1:source/"
      and in all the subdirectories that may be contained in the
      "df1:source" directory.
      Another example: "Lharc -r a archive.lzh df1:*" will archive the
      entire disk in drive df1:, including all its subdirectories.
      (you may wish to add the -a switch to the above line in order to
      be able to re-build exactly the disk, including file attributes)
      Very powerfull, isn't it ?
      When you specify the -r switch, files are always stored with their
      path name, i.e. the -r switch automatically turns on the -x switch,
      too.

  -S  Set sorting criteria          [note that this is an UPPLERCASE S]
      This switch sets the sort criterium for files beeing added to
      archives. The '-S' must be immediatly followed by one or two
      characters, i.e. -Sxy
      'x' can be any of the following:
         0  Don't sort files
         a  Alphabetical sort
         c  Chronological sort
      'y', if present, can be any of the following:
         a  Ascending order
         d  Descending order
      If 'y' is absent, ascending order is assumed by default.
      Examples:
         -Scd          Sort chronologically in descending order
         -Sc  or -Sca  Sort chronologically in ascending order.
         -S0           Don't sort at all
         -Saa          Sort alphabetically in ascending order, this is
                       the default action which is taken if you don't
                       specify this switch.

  -b  Set I/O buffer size
      Big I/O buffers can considerably speed up some operations of Lharc
      (espacially with hard disks) however if you are low on memory you
      may prefer to use small I/O buffers.
      This switch lets you set the amount of memory that Lharc will use
      as an I/O buffer: the number of Kbytes of memory to be used must
      immediately follow the 'b' without any spaces in between, e.g.
      -b20 tells Lharc to use 20 kbytes of memory for I/O buffers.
      Any number between 6 and 37 is valid, default is using 11 Kbytes:
      if you are low on memory you can lower this amount, but if you have
      plenty of memory I suggest that you rise it.
      I suggest that you set this switch at the value you like in the
      environment variable 'LHARC' (see below) so that you don't have
      to specify this switch every time you invoke Lharc.

  -f  Ignore filenotes
      By defaults Lharc archives files complete with their comment
      (filenote). If you set this switch filenotes won't be stored in
      archives and files beeing extracted won't have their filenote
      even if it's present in the archive.
      There is no compatibility problem, but if you are not interested
      in filenotes you may set this switch to reduce the archive size
      (filenotes are stored in uncompressed form, so if you have long
      filenotes they can increase the size of the archive)










 --- Setting switches in an environment variable ---

   You may set any of LHarc's default switches with the environment
   variable 'LHARC':
   So, if you, for example, want to always archive files with their
   attributes, use the maximum allowed I/O buffer size and use
   'dh0:mytemp/' as a working directory you simply type:

   SenEnv LHARC  "-wdh0:mytemp -a -b37"

   (don't forget the quotes): now Lharc will behave as if you typed
   the above switches every time you invoke it. You can insert the
   setenv command in your startup-sequence so that it's automatically
   executed every time you turn your computer on.
   Of course, you can always override the default settings
   estabilisced in the enviroment variable with the command line: for
   example an '-a0' in the command line will override the '-a' found
   in the above enviromnet variable.
   Please note that the 'setenv' command is only available in
   Workbench 1.3 and higher: if you are using older versions of the
   O.S. this feature is not available.










 --- Autoshow files ---

Suppose that your archive contains an important text file that you
want to be sure it will be read by the guy who unpacks the archive.
The file may for example contain a copyright notice or some special
instructions for unpacking (if you have packed the archive with the -a
switch you may wish to remind to the one who unpacks the archive the
he/she has to use the -a switch too).
For this purpuse this version of Lharc introduces autoshow files: while
unpacking an archive, if Lharc encounters a file whose name ends with
".TXT.DISPLAYME" (case is not significant and quotes must not be
included, of course), it first extracts the file (removing the .DISPLAYME
extension) and then displays in a window the text found in that file
waiting for the user to press RETURN before proceeding.
You can add as many autoshow files as you want, for example one at the
beginning and one at the end of the archive.
Autoshowing of files is disabled when the -m switch is active so that
a non-interactive unpacking session is allowed.
Lharc uses the standard CON: device to open a window for displaing text,
so you can insert ANSI codes in your autoshow files to make your
messages nicer. Lharc will adjust the size of the window according to
the number of lines contained in the text file, but the maximum allowed
size is that of an NTSC screen (200 pixels), so if your text is longer
than 20 lines it will scroll away.
Finally, please note that this feature is unique to the Amiga version of
Lharc (for now...) so remember that if your archive will be unpacked on
another machine (or an an Amiga using Lharc version 1.0 or lower)
autoshow files will simply be extracted without displaying them on the
screen; anyway your important text file will still be there for later
reading by the user and no compatibility problems will arise.











 --- Temporary files ---

While compressing files Lharc creates a temporary file called
'Lharc.TMP_XXXXXX' where XXXXXX is a hex digit representing the address
of its own Task structure as returned by Exec's FindTask(NULL).
The reason for the XXXXXX part of the name is that if you run multiple
copies of Lharc at the same time each copy will create its own temporary
file with a different name (usefull for multiline BBSes for example).
Here is how Lharc decides where to store temporary files.
If you specify a path with the -w switch temporary files are stored
there, otherwise if the T:  logical device is assigned they will be
stored in that directory, otherwise they will go to the current
directory.
If you are not using the -w switch, in order to increase compression
speed, I raccomand that you assign T:  to a directory in the ram-disk.
Note however that T:  is usually automatically assigned to 'ram:t' in
the startup-sequence of the standard Workbench, so, unless you have
modified the startup-sequence, you don't have to worry about this.













 --- Corrupted archives ---

This version al Lharc for the Amiga has the capability of automatically
handle corrupted archives.
A Lharc archive is made up of several compressed files each precedeed by
a header containing information about file name, date, lenght,...
To ensure that the archive is not corrupted the header also contains a
16 bit CRC of the file and an 8 bit checksum of the header itself.
If during extraction Lharc finds a corrupted file (i.e. one whose CRC
does not match with the one stored in the header) the file is extracted
anyway, but a warning is printed on the screen.
The worst case comes when the header of a file is corrupted: in this case
the file cannot be extracted even if the file itself is not corrupted.
In this case Lharc will automatically skip the corrupted entry by
starting a search for the next valid entry in the archive and will
print a message like "WARNING: skipping extraneous/corrupted data"
The reason for which it says "extraneous/corrupted" is that an Lharc
archive might happen to contain parts that Lharc cannot recognize as valid
archive entries even it's not corrupted. This happens when you are
extracting files from a self-extracting archive produced by the MSDOS
version of Lharc, since a self-extracting archive contains 8086
extraction code which the Amiga-Lharc sees as extraneous data.
The only extraneous data which is passed without warnings is additional
bytes at the end of an archive: since they are likely to consist of
zero padding due to XMODEM transfer they are totally ignored.












 --- Return codes ---

When Lharc finishes his work, it returns to the operating system one of
3 possible return codes:

 0  Everything was OK  (the message "Operation successful" is printed on
    the screen).
 5  Lharc finished its work, but something went wrong, for example Lharc
    encountred a corrupted entry in the archive, but was able to continue
    extracting/testing the rest of the archive (the message "Operation not
    totally succesful" is printed on the screen).
 20 A fatal error occurred and Lharc was unable to continue its work (an
    appropriate message exlpaining the probelm is printed on the sceen)

Thus you can test the succes of operation in your script files by means
of the 'failat' statement and the 'if warn' test.











 --- Bugs ---

No known known bugs remain in this version.











 ---- Compatibility ---

This program is aimed at full compatibility with the MSDOS version
1.13 of Lharc.
A few little problems might arise from some file names that are legal
under AmigaDOS, but illegal under MSDOS. As a matter of facts AmigaDOS
allows a wider range of file names (almost every caracter in the ASCII
set is allowed and file names can be longer than 8 characters). For
the greatest convenience of Amiga users, I choose not to restrict the
file name range to accomplish the MSDOS rules, but if you expect that
your archives will be unpacked on an MSDOS machine you'd better
rispect the MSDOS limits.
Also note that, although MSODS Lharc version 1.13 CAN extract files
whose names contain lowercase letters, its pattern matching functions
don't work properly with lowercase file names. So if you want to
extract an Amiga-created archive on an MSDOS machine by using pattern
matching functions (for example to extract only some files instead of
the whole archive) you have to create the archive on the Amiga with
the -u switch.
Finally, to attain 100% compatibility you shuold not use the '-a' switch
(see above in the switch descriptions)

Also note that the MSDOS version of Lharc has the additional
capability of extracting files from archives produced by Larc (a
pupular Japanise archive program): this feature will not be
implemented in the Amiga version.












 ---- Acknowledgements ---

First of all I give credit to Haruyasu Yoshizaki for devising such an
efficent compression algorythm as LZHUF.
Second, since the source to the MSDOS version of Lharc is scarcely
portable (lots of 8086 assembler ruotines and MSDOS-dependent C
functions), I had to rewrite the program from scratch. Note however
that for LZHUF compression/decompression I have used as a starting
point a 'C' source for an example of single file compression
which I found on a BBS. Although the code has been now remanaged (and
partially rewritten in assembler by Paolo Toccaceli) it nevertheless
was invaluable to me.
For sake of correctness I quote here the the header found on this
source:

/*
 * LZHUF.C English version 1.0
 * Based on Japanese version 29-NOV-1988
 * LZSS coded by Haruhiko OKUMURA
 * Adaptive Huffman Coding coded by Haruyasu YOSHIZAKI
 * Edited and translated to English by Kenji RIKITAKE
 */

I whish to thank the above people whose work has been of
foundamental importance for this project.
Thanks to Stefan Boberg for suggesting how to store filenotes in the
archive structure that didn't provide space for them.
Many thanks also go to all the people who contributed with suggestions
and bug reports and particularly to Luca Spada for his invaluable beta
testing work.












 --- How to reach me ---

Please send suggestions, comments and bug reports to:

Paolo Zibetti       Fidonet 2:331/101.6

node 2:331/101 (AmnesiA) is also the official distribution node for
Amiga-Lharc: you'll always find the latest version available on this
board. If you are an officially listed FidoNet node you can f'request
the latest version of Lharc with the magic file name AMILHARC.

Amnesia (2:331/101)  phone [phone]  (v32/HST, upto 14400 bps)



For those who don't have access to a FidoNet node, my Fidonet point
can also be reached from Internet/UUCP at the following address:

[e-mail]